feat(appkit): generate the database operation registry and browser contracts - #690

What did you change, and why?

Why: A compiled server has no TypeScript sources to scan, and the browser needs operation types without importing server code.

Change (build time only):

• Scans server/database/routes/*.ts and writes server/database/routes.gen.ts, a lazy-import registry that satisfies DatabaseRoutes, and shared/appkit-types/database-operations.d.ts, the exact JSON contract of each operation.
• The Vite plugin and appkit generate-types run it. With NODE_ENV=production, an operation without authorization fails generation. An unsupported Zod schema fails with the operation and the slot it came from.
• Operations without an input schema generate input: void, regardless of HTTP method, primary keys, or writable columns. Explicit input schemas still render their exact wire types. Operations without an output schema generate output: void, and explicit output schemas render their exact wire types.
• CI type-checks the built declarations and runs a bundled server that loads its operations without sources.
• A declared schema generates a canonical empty registry before the first operation exists. Adding the first route and removing the last route update that registry; an app with neither schema nor routes creates nothing.
• Watches shared modules throughout server/database/, including row schemas and policies. Generated .gen.ts and .d.ts files are excluded to prevent generation loops.
• Safe to deploy alone: generation does not register HTTP handlers.

Interface

Generation scans the *.ts files directly in server/database/routes/ (skipping *.test.ts, *.d.ts, and *.gen.ts) and writes two files that apps commit. For the playground of the last PR of this stack:

// server/database/routes.gen.ts: consumed by the database plugin
import type { DatabaseRoutes } from "@databricks/appkit/beta";

export const databaseRoutes = {
  schema: () => import("../../config/database/schema"),
  modules: [
    { file: "server/database/routes/boards.ts", load: () => import("./routes/boards") },
    { file: "server/database/routes/notes.ts", load: () => import("./routes/notes") },
  ],
} satisfies DatabaseRoutes;

// shared/appkit-types/database-operations.d.ts: the browser client reads these types
declare global {
  interface DatabricksAppKitDatabaseOperations {
    "notes.update": {
      method: "PATCH";
      input: { "id": number; "body": string };
      output: { "id": number; "board_id": number; "author": string; "body": string; "created_at": string };
    };
    "notes.delete": { method: "DELETE"; input: { "id": number }; output: void };
    "notes.count": { method: "GET"; input: void; output: number };
  }
}

• The AppKit Vite plugin runs it when the dev server starts and when files under config/database/ or server/database/ change, including shared schemas and policies. Generated outputs do not trigger another run. appkit generate-types runs it from the CLI.
• An operation without authorize is skipped with a warning naming its file#export. With NODE_ENV=production, it fails generation instead.
• A Zod schema the client cannot type exactly fails generation with the operation and the slot: z.date(), tuples, z.json(), output transforms, coercion, and preprocessing. A failed run writes an empty interface.

How do you know it works?

Testing: Operation generation, generated wire-type equality, and Vite integration pass with the rest of the type generator (626 tests at this layer). A schema that throws on import fails generation and neutralizes the contracts. Coverage includes shared schema/policy add/change/unlink events, ignored generated files, schema-only bootstrapping, final route deletion, strict mode, and explicit/omitted input contracts. The source-less production bundle check loads all three operations under plain Node after TypeScript sources are removed. Repository build, docs, lint/format, and recursive typechecks pass.

Stack

#683 → #687 → #688 → #689 → #690 → #691 → #692

Design: #683. Previous layer: #689. Next layer: #691.

Review feedback: refactor(appkit): generate void outputs for operations without an output schema drops the entity check and the default output type, and keeps loading the schema so a broken import still neutralizes the contracts.

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}